/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.beanutils;

import java.util.Map;
import java.util.WeakHashMap;

/**
 * An instance of this class represents a value that is provided per (thread) context classloader.
 * 
 * <p>
 * Occasionally it is necessary to store data in "global" variables (including uses of the Singleton pattern). In applications which have only a
 * single classloader such data can simply be stored as "static" members on some class. When multiple classloaders are involved, however, this
 * approach can fail; in particular, this doesn't work when the code may be run within a servlet container or a j2ee container, and the class on which
 * the static member is defined is loaded via a "shared" classloader that is visible to all components running within the container. This class
 * provides a mechanism for associating data with a ClassLoader instance, which ensures that when the code runs in such a container each component
 * gets its own copy of the "global" variable rather than unexpectedly sharing a single copy of the variable with other components that happen to be
 * running in the same container at the same time (eg servlets or EJBs.)
 * </p>
 * 
 * <p>
 * This class is strongly patterned after the java.lang.ThreadLocal class, which performs a similar task in allowing data to be associated with a
 * particular thread.
 * </p>
 * 
 * <p>
 * When code that uses this class is run as a "normal" application, ie not within a container, the effect is identical to just using a static member
 * variable to store the data, because Thread.getContextClassLoader always returns the same classloader (the system classloader).
 * </p>
 * 
 * <p>
 * Expected usage is as follows:<br>
 * 
 * <pre>
 *  public class SomeClass {
 *    private static final ContextClassLoaderLocal global 
 *      = new ContextClassLoaderLocal() {
 *          protected Object initialValue() {
 *              return new String("Initial value");
 *          };
 * 
 *    public void testGlobal() {
 *      String s = (String) global.get();
 *      System.out.println("global value:" + s);
 *      buf.set("New Value");
 *    }
 * </pre>
 * 
 * </p>
 * 
 * <p>
 * <strong>Note:</strong> This class takes some care to ensure that when a component which uses this class is "undeployed" by a container the
 * component-specific classloader and all its associated classes (and their static variables) are garbage-collected. Unfortunately there is one
 * scenario in which this does <i>not</i> work correctly and there is unfortunately no known workaround other than ensuring that the component (or its
 * container) calls the "unset" method on this class for each instance of this class when the component is undeployed. The problem occurs if:
 * <ul>
 * <li>the class containing a static instance of this class was loaded via a shared classloader, and</li>
 * <li>the value stored in the instance is an object whose class was loaded via the component-specific classloader (or any of the objects it refers to
 * were loaded via that classloader).</li>
 * </ul>
 * The result is that the map managed by this object still contains a strong reference to the stored object, which contains a strong reference to the
 * classloader that loaded it, meaning that although the container has "undeployed" the component the component-specific classloader and all the
 * related classes and static variables cannot be garbage-collected. This is not expected to be an issue with the commons-beanutils library as the
 * only classes which use this class are BeanUtilsBean and ConvertUtilsBean and there is no obvious reason for a user of the beanutils library to
 * subclass either of those classes.
 * </p>
 * 
 * <p>
 * <strong>Note:</strong> A WeakHashMap bug in several 1.3 JVMs results in a memory leak for those JVMs.
 * </p>
 * 
 * <p>
 * <strong>Note:</strong> Of course all of this would be unnecessary if containers required each component to load the full set of classes it needs,
 * ie avoided providing classes loaded via a "shared" classloader.
 * </p>
 * 
 * @see java.lang.Thread#getContextClassLoader
 * @author Eric Pabst
 */
public class ContextClassLoaderLocal {
    private Map valueByClassLoader = new WeakHashMap();
    private boolean globalValueInitialized = false;
    private Object globalValue;

    /**
     * Construct a context classloader instance
     */
    public ContextClassLoaderLocal() {
        super();
    }

    /**
     * Returns the initial value for this ContextClassLoaderLocal variable. This method will be called once per Context ClassLoader for each
     * ContextClassLoaderLocal, the first time it is accessed with get or set. If the programmer desires ContextClassLoaderLocal variables to be
     * initialized to some value other than null, ContextClassLoaderLocal must be subclassed, and this method overridden. Typically, an anonymous
     * inner class will be used. Typical implementations of initialValue will call an appropriate constructor and return the newly constructed object.
     * 
     * @return a new Object to be used as an initial value for this ContextClassLoaderLocal
     */
    protected Object initialValue() {
        return null;
    }

    /**
     * Gets the instance which provides the functionality for {@link BeanUtils}. This is a pseudo-singleton - an single instance is provided per
     * (thread) context classloader. This mechanism provides isolation for web apps deployed in the same container.
     * 
     * @return the object currently associated with the context-classloader of the current thread.
     */
    public synchronized Object get() {
        // synchronizing the whole method is a bit slower 
        // but guarantees no subtle threading problems, and there's no 
        // need to synchronize valueByClassLoader

        // make sure that the map is given a change to purge itself
        valueByClassLoader.isEmpty();
        try {

            ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
            if (contextClassLoader != null) {

                Object value = valueByClassLoader.get(contextClassLoader);
                if ((value == null) && !valueByClassLoader.containsKey(contextClassLoader)) {
                    value = initialValue();
                    valueByClassLoader.put(contextClassLoader, value);
                }
                return value;

            }

        } catch (SecurityException e) { /* SWALLOW - should we log this? */
        }

        // if none or exception, return the globalValue 
        if (!globalValueInitialized) {
            globalValue = initialValue();
            globalValueInitialized = true;
        }//else already set
        return globalValue;
    }

    /**
     * Sets the value - a value is provided per (thread) context classloader. This mechanism provides isolation for web apps deployed in the same
     * container.
     * 
     * @param value
     *            the object to be associated with the entrant thread's context classloader
     */
    public synchronized void set(Object value) {
        // synchronizing the whole method is a bit slower 
        // but guarentees no subtle threading problems

        // make sure that the map is given a change to purge itself
        valueByClassLoader.isEmpty();
        try {

            ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
            if (contextClassLoader != null) {
                valueByClassLoader.put(contextClassLoader, value);
                return;
            }

        } catch (SecurityException e) { /* SWALLOW - should we log this? */
        }

        // if in doubt, set the global value
        globalValue = value;
        globalValueInitialized = true;
    }

    /**
     * Unsets the value associated with the current thread's context classloader
     */
    public synchronized void unset() {
        try {

            ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
            unset(contextClassLoader);

        } catch (SecurityException e) { /* SWALLOW - should we log this? */
        }
    }

    /**
     * Unsets the value associated with the given classloader
     * 
     * @param classLoader
     *            The classloader to <i>unset</i> for
     */
    public synchronized void unset(ClassLoader classLoader) {
        valueByClassLoader.remove(classLoader);
    }
}
